<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>safe_signed_range&lt;MIN, MAX, PP, EP&gt; and safe_unsigned_range&lt;MIN, MAX, PP, EP&gt;</title>
<link rel="stylesheet" href="boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Safe Numerics">
<link rel="up" href="types.html" title="Types">
<link rel="prev" href="safe.html" title="safe&lt;T, PP, EP&gt;">
<link rel="next" href="safe_literal.html" title="safe_signed_literal&lt;Value, PP , EP&gt; and safe_unsigned_literal&lt;Value, PP, EP&gt;">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img href="index.html" height="164px" src="pre-boost.jpg" alt="Library Documentation Index"></td>
<td><h2>Safe Numerics</h2></td>
</tr></table>
<div class="spirit-nav">
<a accesskey="p" href="safe.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="types.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="safe_literal.html"><img src="images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="safe_numerics.safe_range"></a>safe_signed_range&lt;MIN, MAX, PP, EP&gt; and
  safe_unsigned_range&lt;MIN, MAX, PP, EP&gt;</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="safe_range.html#idm462684558896">Description</a></span></dt>
<dt><span class="section"><a href="safe_range.html#idm462684556016">Notation</a></span></dt>
<dt><span class="section"><a href="safe_range.html#idm462684548656">Associated Types</a></span></dt>
<dt><span class="section"><a href="safe_range.html#idm462684541568">Template Parameters</a></span></dt>
<dt><span class="section"><a href="safe_range.html#idm462684517440">Model of</a></span></dt>
<dt><span class="section"><a href="safe_range.html#idm462684514832">Valid Expressions</a></span></dt>
<dt><span class="section"><a href="safe_range.html#idm462684508320">Example of use</a></span></dt>
<dt><span class="section"><a href="safe_range.html#idm462684358368">Header</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm462684558896"></a>Description</h4></div></div></div>
<p>This type holds a signed or unsigned integer in the closed range
    [MIN, MAX]. A <code class="computeroutput">safe_signed_range&lt;MIN, MAX, PP, EP&gt;</code> or
    <code class="computeroutput">safe_unsigned_range&lt;MIN, MAX, PP, EP&gt;</code> can be used
    anywhere an arithmetic type is permitted. Any expression which uses either
    of these types is guaranteed to return an arithmetically correct value or
    to trap in some way.</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm462684556016"></a>Notation</h4></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col align="left">
<col align="left">
</colgroup>
<thead><tr>
<th align="left">Symbol</th>
<th align="left">Description</th>
</tr></thead>
<tbody><tr>
<td align="left"><code class="computeroutput">MIN, MAX</code></td>
<td align="left">Minimum and maximum values that the range can
            represent.</td>
</tr></tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm462684548656"></a>Associated Types</h4></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col align="left">
<col align="left">
</colgroup>
<tbody>
<tr>
<td align="left"><code class="computeroutput">PP</code></td>
<td align="left">Promotion Policy. A type which specifies the result type of
            an expression using safe types.</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">EP</code></td>
<td align="left">Exception Policy. A type containing members which are
            called when a correct result cannot be returned</td>
</tr>
</tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm462684541568"></a>Template Parameters</h4></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col align="left">
<col align="left">
<col align="left">
</colgroup>
<thead><tr>
<th align="left">Parameter</th>
<th align="left">Requirements</th>
<th align="left">Description</th>
</tr></thead>
<tbody>
<tr>
<td align="left"><code class="computeroutput">T</code></td>
<td align="left"><a class="link" href="integer_concept.html" title="Integer&lt;T&gt;">std::is_integer&lt;T&gt;</a></td>
<td align="left"><p>The underlying type. Currently only built-in integer
            types are supported</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">MIN</code></td>
<td align="left">must be a non-negative literal</td>
<td align="left">The minimum non-negative integer value that this type may
            hold</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">MAX</code></td>
<td align="left">must be a non-negative literal</td>
<td align="left">The maximum non-negative integer value that this type may
            hold</td>
</tr>
<tr>
<td align="left"> </td>
<td align="left">MIN &lt;= MAX</td>
<td align="left">must be a valid closed range</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">PP</code></td>
<td align="left"><a class="link" href="">PromotionPolicy&lt;PP&gt;</a></td>
<td align="left"><p>Default value is <a class="link" href="promotion_policies/native.html" title="native"><code class="computeroutput">boost::numeric::native</code></a></p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">EP</code></td>
<td align="left"><a class="link" href="">Exception
            Policy&lt;EP&gt;</a></td>
<td align="left"><p>Default value is <a class="link" href="exception_policies.html#safe_numerics.exception_policies.default_exception_policy"><code class="computeroutput">boost::numeric::default_exception_policy</code></a></p></td>
</tr>
</tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm462684517440"></a>Model of</h4></div></div></div>
<p><a class="link" href="numeric_concept.html" title="Numeric&lt;T&gt;">Numeric</a></p>
<p><a class="link" href="integer_concept.html" title="Integer&lt;T&gt;">Integer</a></p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm462684514832"></a>Valid Expressions</h4></div></div></div>
<p>Implements all expressions and only those expressions supported by
    the base type T. Note that all these expressions are
    <code class="computeroutput">constexpr</code>. The result type of such an expression will be
    another safe type. The actual type of the result of such an expression
    will depend upon the specific promotion policy template parameter.</p>
<p>When a binary operand is applied to two instances of A
    <code class="computeroutput">safe_signed_range&lt;MIN, MAX, PP, EP&gt;</code> or
    <code class="computeroutput">safe_unsigned_range&lt;MIN, MAX, PP, EP&gt;</code> one of the
    following must be true:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>The promotion policies of the two operands must be the same or
          one of them must be void</p></li>
<li class="listitem"><p>The exception policies of the two operands must be the same or
          one of them must be void</p></li>
</ul></div>
<p>If either of the above is not true, a compile error will
    result.</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm462684508320"></a>Example of use</h4></div></div></div>
<pre class="programlisting"><span class="comment">//  Copyright (c) 2018 Robert Ramey</span>
<span class="comment">//</span>
<span class="comment">// Distributed under the Boost Software License, Version 1.0. (See</span>
<span class="comment">// accompanying file LICENSE_1_0.txt or copy at</span>
<span class="comment">// http://www.boost.org/LICENSE_1_0.txt)</span>

<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">exception</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">type_traits</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">safe_numerics</span><span class="special">/</span><span class="identifier">safe_integer</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">safe_numerics</span><span class="special">/</span><span class="identifier">safe_integer_range</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">safe_numerics</span><span class="special">/</span><span class="identifier">safe_integer_literal</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>

<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">safe_numerics</span><span class="special">/</span><span class="identifier">utility</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>

<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">safe_numerics</span><span class="special">;</span>

<span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="special">)</span><span class="special">{</span>
    <span class="identifier">safe_unsigned_range</span><span class="special">&lt;</span><span class="number">7</span><span class="special">,</span> <span class="number">24</span><span class="special">&gt;</span> <span class="identifier">i</span><span class="special">;</span>
    
    <span class="comment">// since the range is included in [0,255], the underlying type of i</span>
    <span class="comment">// will be an unsigned char.</span>
    <span class="keyword">try</span><span class="special">{</span>
        <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>  <span class="comment">// throws out_of_range exception</span>
        <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"fails to detect erroneous assignment"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
    <span class="special">}</span>
    <span class="keyword">catch</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span> <span class="special">&amp;</span> <span class="identifier">e</span><span class="special">)</span><span class="special">{</span>
        <span class="comment">// should arrive here</span>
    <span class="special">}</span>
    <span class="keyword">try</span><span class="special">{</span>
        <span class="identifier">i</span> <span class="special">=</span> <span class="number">9</span><span class="special">;</span>  <span class="comment">// ok - no exception expected</span>
    <span class="special">}</span>
    <span class="keyword">catch</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span> <span class="special">&amp;</span> <span class="identifier">e</span><span class="special">)</span><span class="special">{</span>
        <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"erroneous error for legal assignment"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
    <span class="special">}</span>
    <span class="keyword">try</span><span class="special">{</span>
        <span class="identifier">i</span> <span class="special">*=</span> <span class="number">9</span><span class="special">;</span> <span class="comment">// fails to compile because result can't fin in range</span>
        <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"fails to out of range result"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
    <span class="special">}</span>
    <span class="keyword">catch</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span> <span class="special">&amp;</span> <span class="identifier">e</span><span class="special">)</span><span class="special">{</span>
        <span class="comment">// should arrive here</span>
    <span class="special">}</span>
    <span class="keyword">try</span><span class="special">{</span>
        <span class="identifier">i</span> <span class="special">=</span> <span class="special">-</span><span class="number">1</span><span class="special">;</span> <span class="comment">// throws out_of_range exception</span>
        <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"fails to detect erroneous assignment"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
    <span class="special">}</span>
    <span class="keyword">catch</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span> <span class="special">&amp;</span> <span class="identifier">e</span><span class="special">)</span><span class="special">{</span>
        <span class="comment">// should arrive here</span>
    <span class="special">}</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">uint8_t</span> <span class="identifier">j</span> <span class="special">=</span> <span class="number">4</span><span class="special">;</span>
    <span class="keyword">auto</span> <span class="identifier">k</span> <span class="special">=</span> <span class="identifier">i</span> <span class="special">+</span> <span class="identifier">j</span><span class="special">;</span>

    <span class="comment">// if either or both types are safe types, the result is a safe type</span>
    <span class="comment">// determined by promotion policy.  In this instance</span>
    <span class="comment">// the range of i is [7, 24] and the range of j is [0,255].</span>
    <span class="comment">// so the type of k will be a safe type with a range of [7,279]</span>
    <span class="identifier">static_assert</span><span class="special">(</span>
        <span class="identifier">is_safe</span><span class="special">&lt;</span><span class="keyword">decltype</span><span class="special">(</span><span class="identifier">k</span><span class="special">)</span><span class="special">&gt;</span><span class="special">::</span><span class="identifier">value</span>
        <span class="special">&amp;&amp;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">decltype</span><span class="special">(</span><span class="identifier">k</span><span class="special">)</span><span class="special">&gt;</span><span class="special">::</span><span class="identifier">min</span><span class="special">(</span><span class="special">)</span> <span class="special">==</span> <span class="number">7</span>
        <span class="special">&amp;&amp;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">decltype</span><span class="special">(</span><span class="identifier">k</span><span class="special">)</span><span class="special">&gt;</span><span class="special">::</span><span class="identifier">max</span><span class="special">(</span><span class="special">)</span> <span class="special">==</span> <span class="number">279</span><span class="special">,</span>
        <span class="string">"k is a safe range of [7,279]"</span>
    <span class="special">)</span><span class="special">;</span>
    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm462684358368"></a>Header</h4></div></div></div>
<p><code class="filename"><a href="../../include/boost/safe_numerics/safe_integer_range.hpp" target="_top">#include
    &lt;boost/numeric/safe_numerics/safe_range.hpp&gt;</a></code></p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2012-2018 Robert Ramey<p><a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">Subject to Boost
      Software License</a></p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="safe.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="types.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="safe_literal.html"><img src="images/next.png" alt="Next"></a>
</div>
</body>
</html>
